home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 43 / Amiga Format CD43 (1999)(Future Publishing)(GB)(Track 1 of 2)[!][issue 1999-09].iso / -serious- / comms / other / ums / tools / flushlibrary / flush.doc < prev    next >
Text File  |  1999-06-14  |  8KB  |  258 lines
  1.  
  2.  
  3. TABLE OF CONTENTS
  4.  
  5. flush.library/README
  6. flush.library/FlushDo()
  7. flush.library/FlushEnableAnnounce()
  8. flush.library/FlushDisableAnnounce()
  9.  
  10.  
  11. flush.library/README                             flush.library/README
  12.  
  13.    FLUSH LIBRARY
  14.     This library has been designed to allow easy notification if
  15.     memory is getting low. Programs which desire this information
  16.     have to ask for it at initialization, and to "unsubscribe" at
  17.     cleanup. A safe way to do this is to subscribe AFTER having
  18.     allocated everything, and unsubscribe BEFORE freeing the memory.
  19.  
  20.    NOTES
  21.     - The library must remain open until you have no subscribe pending.
  22.     - Note that you may subscribe more than once.
  23.     - You may also subscribe/unsubscribe for other tasks.
  24.     - Note that the open count will be always zero. This is a side effect
  25.     and has no influence on the library or system itself.
  26.  
  27.    VERSION
  28.     1.1
  29.  
  30.    NEW FOR THIS RELEASE
  31.     MODE_MSG has been implemented. See FlushEnableAnnounce().
  32.     C-Support (C definitions by Michel Schinz)
  33.  
  34.    AUTHORS
  35.     Marc Schaefer (general design and implementation)
  36.     Michel Schinz (C include files and definitions.)
  37.     For more information see COPYRIGHT, README, HISTORY, and BUG files.
  38.  
  39.    SEE ALSO
  40.     exec.library/OpenLibrary()
  41.     exec.library/CloseLibrary()
  42.     flush.library/FlushEnableAnnounce()
  43.  
  44.    BUGS
  45.     None known.
  46.  
  47.    TODO
  48.     No more ideas.
  49.  
  50.  
  51. flush.library/FlushDo()                           flush.library/FlushDo()
  52.  
  53.    NAME
  54.     FlushDo -- Announce flush event to all tasks / handler that asked
  55.                    for it with FlushEnableAnnounce()
  56.  
  57.    SYNOPSIS
  58.     FlushDo()
  59.  
  60.     void FlushDo();
  61.  
  62.    FUNCTION
  63.     Announce a flush event to all tasks and handlers who have asked
  64.     for it via FlushEnableAnnounce(), and have not "unsubscribed"
  65.     with FlushDisableAnnounce().
  66.  
  67.    INPUTS
  68.     None
  69.  
  70.    RETURNS
  71.     None
  72.  
  73.    NOTES
  74.     - This call is not safe from interrupts, since it is not possible
  75.     to free memory (= access memory lists) during interrupts. See
  76.     Exec AllocMem() and FreeMem().
  77.     - This call is safe within a Forbid(), or AllocMem().
  78.     - We don't scratch _any_ register. No return code. As a normal
  79.     library we need our basepointer in A6.
  80.     - We will panic if any node is an illegal state, using Exec/Alert().
  81.  
  82.    SEE ALSO
  83.     exec.library/Alert()
  84.     exec.library/AllocMem()
  85.     exec.library/FreeMem()
  86.     exec.library/Forbid()
  87.     exec.library/Permit()
  88.     flush.library/FlushEnableAnnounce()
  89.     flush.library/FlushDisableAnnounce()
  90.  
  91.    BUGS
  92.     None known.
  93.  
  94.    TODO
  95.     No more ideas.
  96.  
  97.  
  98. flush.library/FlushEnableAnnounce()                           flush.library/FlushEnableAnnounce()
  99.  
  100.    NAME
  101.     FlushEnableAnnounce -- Inform library that we want Flush information.
  102.  
  103.    SYNOPSIS
  104.     flushid = FlushEnableAnnounce(mode, handler, data, pri)
  105.     D0                            D0    A0       D1    D2-0:8
  106.  
  107.     ULONG FlushEnableAnnounce(ULONG, APTR, ULONG, LONG);
  108.  
  109.    FUNCTION
  110.     Subscribe for flush event announce. The following modes apply:
  111.  
  112.     MODE_SIGNALME        The task specified in handler will receive
  113.                 the signal bit number data (low 8 bits only).
  114.  
  115.     MODE_HANDLER        FlushDo will directly jump to the specified
  116.                 address handler with the following registers set:
  117.  
  118.                 A6 ^ ExecBase
  119.                 D0 = the value submitted as 'data'.
  120.  
  121.                 You may not scratch any registers EXCEPT
  122.                 A0/A1/D0/D1 (normal convention) and A6 (special
  123.                 convention). Note that the stack given to you
  124.                 will be a the stack of the process that caused
  125.                 the low memory AllocMem() flush.
  126.                 You may not do anything that could cause you
  127.                 to Wait() or take long to complete. And don't
  128.                 allocate memory !! You are probably called from
  129.                 inside the memory allocator !
  130.  
  131.     MODE_MSG        We will reply to the message specified in handler and
  132.                 immediately do a FlushDisableAnnounce() for you, since
  133.                 we don't own your message any more. You should always
  134.                 do as follows to unsubscribe.
  135.                     a) Check that you did not already receive the message if you
  136.                     have an internal boolean variable.
  137.                     b) Forbid()
  138.                     c) Check that you didn't receive the message with GetMessage().
  139.                     d) FlushDisableAnnounce(flushid) if message not received.
  140.                     e) Permit()
  141.                     f) General cleanup.
  142.                 The only advantage of this method is that we free our internal
  143.                 structure synchronously. However in most cases you better should
  144.                 use MODE_HANDLER or MODE_SIGNALME.
  145.                 Note that the message structure should be properly initalized (ReplyPort set)
  146.                 
  147.     Note that MODE_SIGNALME does not authorize direct freeing, because
  148.     of multitasking rules, but allow you to Wait() or call any function
  149.     your task may normally call. The call to AllocMem() that caused the
  150.     Flush _will_ infact fail. It's the simplest, but also the less useful
  151.     method since memory isn't de-allocated synchronously.
  152.  
  153.     MODE_HANDLER will be preferred mode for programs that really want the
  154.     low-memory situation to be quickly resolved. If there is sufficient
  155.     memory freed by MODE_HANDLER's routines, the AllocMem() call that
  156.     caused the flush will succeed. It's the better method for resource-freeing,
  157.     but a dangerous one since you are called from the Memory Allocator.
  158.  
  159.     MODE_MSG will be preferred method for programs that have no more signal to
  160.     be allocated and would perfer using a special message port shared between more
  161.     events. However you should better consider the complexity of the task before
  162.     choosing this method. Note that you may also use special features of the
  163.     messages ports such as software interrupts.
  164.  
  165.    INPUTS
  166.     mode - either MODE_SIGNALME, MODE_HANDLER or MODE_MSG.
  167.     handler - either a pointer to a task control block, or to a handler.
  168.     data - either the signal bit number or a data passed as a parameter.
  169.     pri - the priority of your node (-128 ... +127), zero for normal.
  170.  
  171.    RETURNS
  172.     flushid - 0 if memory problem (don't call FlushDisableAnnounce() then).
  173.     You have to save this somewhere for giving it back as an argument
  174.     to FlushDisableAnnounce().
  175.  
  176.    NOTES
  177.     - This call should be done during (after) initialization. At the
  178.     time you call this routine, your handler may be called, or your
  179.     task being signaled.
  180.     - We don't allow message-based information, because allocating a
  181.     message during a flush is not possible, however replying to a message
  182.     previously received would be possible.
  183.     - Not safe from interrupts. We only Forbid() to get access to our
  184.     internal list. We also allocate memory, which is not allowed from
  185.     interrupts (see exec.library/AllocMem())
  186.     - We don't scratch _any_ register, except D0 for return code. As a normal
  187.     library we need our basepointer in A6.
  188.     - We will panic if the mode is illegal, using Exec/Alert().
  189.  
  190.    SEE ALSO
  191.     exec.library/Alert()
  192.     exec.library/AllocMem()
  193.     exec.library/FreeMem()
  194.     exec.library/Forbid()
  195.     exec.library/Permit()
  196.     exec.library/Wait()
  197.     flush.library/FlushEnableAnnounce()
  198.     flush.library/FlushDisableAnnounce()
  199.     flush.library/FlushDo()
  200.  
  201.    BUGS
  202.     None known.
  203.  
  204.    TODO
  205.     No more ideas.
  206.  
  207.  
  208. flush.library/FlushDisableAnnounce()                           flush.library/FlushDisableAnnounce()
  209.  
  210.    NAME
  211.     FlushDisableAnnounce -- Inform library that we don't want Flush information any more.
  212.  
  213.    SYNOPSIS
  214.     FlushDisableAnnounce(flushid)
  215.                          D0
  216.  
  217.     void FlushDisableAnnounce(ULONG);
  218.  
  219.    FUNCTION
  220.     Unsubscribe for flush event announce. This routine is normally called
  221.     if you succeeded with FlushEnableAnnounce() and you are just before
  222.     clean up. It is important NOT to let the flush notification enabled
  223.     if you quit or clean up. This may result in memory trashing or free
  224.     twice bugs. Note that if MODE_MSG was the choosen mode, we WON'T
  225.     reply to the message. Infact the message field will be ignored.
  226.  
  227.    INPUTS
  228.     flushid - what was returned from FlushEnableAnnounce().
  229.  
  230.    RETURNS
  231.     None.
  232.  
  233.    NOTES
  234.     - Not safe from interrupts. We only Forbid() to get access to our
  235.     internal list. We free memory.
  236.     - We don't scratch _any_ register, except D0 (information invalid).
  237.     As a normal library we need our basepointer in A6.
  238.     - We will panic if the node contains illegal information or is nil,
  239.     using Exec/Alert().
  240.  
  241.    SEE ALSO
  242.     exec.library/Alert()
  243.     exec.library/AllocMem()
  244.     exec.library/FreeMem()
  245.     exec.library/Forbid()
  246.     exec.library/Permit()
  247.     flush.library/FlushEnableAnnounce()
  248.     flush.library/FlushDisableAnnounce()
  249.     flush.library/FlushDo()
  250.  
  251.    BUGS
  252.     None known.
  253.  
  254.    TODO
  255.     No more ideas.
  256.  
  257.  
  258.